.\"     Title: ne_session_create
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
.\"      Date: 20 August 2008
.\"    Manual: neon API reference
.\"    Source: neon 0.28.3
.\"
.TH "NE_SESSION_CREATE" "3" "20 August 2008" "neon 0.28.3" "neon API reference"
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
ne_session_create, ne_close_connection, ne_session_proxy, ne_session_destroy - set up HTTP sessions
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <ne_session\.h>
.fi
.ft
.HP 30
.BI "ne_session *ne_session_create(const\ char\ *" "scheme" ", const\ char\ *" "hostname" ", unsigned\ int\ " "port" ");"
.HP 22
.BI "void ne_session_proxy(ne_session\ *" "session" ", const\ char\ *" "hostname" ", unsigned\ int\ " "port" ");"
.HP 25
.BI "void ne_close_connection(ne_session\ *" "session" ");"
.HP 24
.BI "void ne_session_destroy(ne_session\ *" "session" ");"
.SH "DESCRIPTION"
.PP
An
\fBne_session\fR
object represents an HTTP session \- a logical grouping of a sequence of HTTP requests made to a certain server\. Any requests made using the session can use a persistent connection, share cached authentication credentials and any other common attributes\.
.PP
A new HTTP session is created using
\fBne_session_create\fR, giving the
\fIhostname\fR
and
\fIport\fR
of the server to use, along with the
\fIscheme\fR
used to contact the server (usually
"http")\. Before the first use of
\fBne_session_create\fR
in a process,
ne_sock_init
must have been called to perform any global initialization needed by any libraries used by neon\.
.PP
To enable SSL/TLS for the session, pass the string
"https"
as the
\fIscheme\fR
parameter, and either register a certificate verification function (see
ne_ssl_set_verify) or trust the appropriate certificate (see
ne_ssl_trust_cert,
ne_ssl_trust_default_ca)\.
.PP
If an HTTP proxy server should be used for the session,
\fBne_session_proxy\fR
must be called giving the hostname and port on which to contact the proxy\.
.PP
Further per\-session options may be changed using the
ne_set_request_flag
interface\.
.PP
If it is known that the session will not be used for a significant period of time,
\fBne_close_connection\fR
can be called to close the connection, if one remains open\. Use of this function is entirely optional, but it must not be called if there is a request active using the session\.
.PP
Once a session has been completed,
\fBne_session_destroy\fR
must be called to destroy the resources associated with the session\. Any subsequent use of the session pointer produces undefined behaviour\.
.SH "NOTES"
.PP
The hostname passed to
\fBne_session_create\fR
is resolved when the first request using the session is dispatched; a DNS resolution failure can only be detected at that time (using the
NE_LOOKUP
error code); see
ne_request_dispatch
for details\.
.SH "RETURN VALUES"
.PP
\fBne_session_create\fR
will return a pointer to a new session object (and never
NULL)\.
.SH "EXAMPLES"
.PP
Create and destroy a session:
.sp
.RS 4
.nf
ne_session *sess;
sess = ne_session_create("http", "host\.example\.com", 80);
/* \.\.\. use sess \.\.\. */
ne_session_destroy(sess);
.fi
.RE
.SH "SEE ALSO"
.PP
ne_ssl_set_verify,
ne_ssl_trust_cert,
ne_sock_init,
ne_set_session_flag
.SH "AUTHOR"
.PP
\fBJoe Orton\fR <\&neon@lists.manyfish.co.uk\&>
.sp -1n
.IP "" 4
Author.
.SH "COPYRIGHT"
